# Debug UART

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**Debug Uart** 是 **Quectel Pi M1/L1** 的调试串口控制台，用于通过 USB 转 TTL 串口工具连接开发板，在电脑端查看启动日志、进入系统控制台并执行调试命令。与 SSH、VNC 等网络方式不同，Debug Uart 不依赖网络和图形界面，适合系统启动、网络异常、显示异常等底层问题排查场景。

# 准备工作

1. 准备一个 **USB 转 TTL 串口小板** 和 3 根杜邦线。请确认串口小板支持 **3.3 V** 电平。  
  ```{image} images/image_KVArbtG3comAoFxey4NcsbMsnjf.webp
  :width: 1382px
  :height: 389px
  ```

2. 确认 **Quectel Pi M1 / L1** 的 Debug Uart 接口位置，并按接线示意图连接串口线。  
  > 💡 使用 USB 串口数据线连接智能主控板时，请确认引脚连接正确。接错引脚可能导致串口无法通信，严重时可能损坏硬件。  
  <div class="sd-container-fluid">
  <div class="sd-row">
  <div class="sd-col sd-col-6">
  <img src="images/image_YAJ5bBQAZoN5sMxAiFpcEbVxnLb.webp" alt="image" width="390" height="600">
  </div>

  <div class="sd-col sd-col-6">
  <img src="images/image_LBPwbVnb9odIujxLvg3cfISSnTf.webp" alt="image" width="458" height="600">
  </div>

  </div>
  </div>


3. 将 USB 转 TTL 串口小板接入电脑，确认电脑可以识别串口号。  
    - Windows：在 **设备管理器** 中查看串口号，例如 `COM8`。  
    - Linux：查看 `/dev/ttyUSB*` 或 `/dev/ttyACM*` 设备节点。

4. 准备串口终端软件。Windows 推荐使用 [QPiTerminal](<https://www.quectel.com.cn/wp-content/uploads/2026/05/QPiTerminal_V1.0.zip>) ,Linux 可使用 `picocom`。

# 软件安装

电脑端需要准备串口终端软件和对应 USB 串口驱动。

## Windows

Windows 推荐使用 **QPiTerminal** 进行串口连接。若电脑无法识别 USB 转 TTL 串口设备，请先安装对应驱动，例如 CH340、CP210x 或 FTDI 驱动，具体以所使用的串口小板芯片为准。

插入 USB 转 TTL 串口小板后，可在 **设备管理器** 中查看对应的串口号，例如 `COM8`。

## Linux

Linux 电脑端通常会识别为 `/dev/ttyUSB*` 或 `/dev/ttyACM*` 设备。可执行以下命令查看：

```bash
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
```

如需使用 `picocom`，可安装：

```bash
sudo apt update
sudo apt install -y picocom
```

# 软件配置

使用 QPiTerminal 时，选择 **Serial** 连接方式，点击 **Open new session**，在弹出的窗口中选择设备管理器识别到的串口号，并将波特率设置为 **115200**。

```{image} images/image_AHfIbiOyroRM14xrACtcxzEOnAe.webp
:width: 1152px
:height: 661px
```

在 **New Serial Session** 窗口中确认串口号和波特率后，点击 **Connect** 建立串口连接。

```{image} images/image_Y7ZfbxhtRoJ2CExo9TSctW0jnDe.webp
:width: 1152px
:height: 661px
```

# 软件启动

Debug Uart 不需要在开发板端单独启动网络服务。硬件接线正确、电脑端驱动和串口终端配置正确后，打开串口终端即可使用。

## Windows 启动 QPiTerminal

1. 将 USB 转 TTL 串口小板接入电脑。

2. 在设备管理器中确认串口号。

3. 打开 QPiTerminal，选择 **Serial** 连接方式。

4. 点击 **Open new session**，选择串口号并设置波特率 **115200**。

5. 点击 **Connect** 打开串口窗口。

## Linux 使用 picocom

在 PC 端执行：

```bash
sudo picocom -b 115200 /dev/ttyUSB0
```

其中 `/dev/ttyUSB0` 需根据实际识别到的设备节点替换。

退出 `picocom` 可按：

```
Ctrl+A，然后 Ctrl+X
```

# 串口控制台

打开串口终端后，给开发板上电或重启，即可看到启动日志。系统启动完成后，可在终端界面按 **Enter**，再输入命令进行测试。

```bash
ls
```

若能看到系统目录列表，表示串口控制台可正常使用。

```{image} images/image_TlzbbZuVSoBrKbxdQ05c3HtCnJh.webp
:width: 1152px
:height: 661px
```

# 疑难解答

| **问题现象** | **排查方法** |
| --- | --- |
| 电脑端没有串口号 | 检查 USB 转 TTL 串口小板是否插好；确认已安装对应驱动；更换 USB 线或 USB 口后重试。 |
| 串口窗口无输出 | 检查 GND、TXD、RXD 是否接对；确认 TXD 连接到 RXD、RXD 连接到 TXD；确认串口电平为 3.3 V。 |
| 输出乱码 | 检查波特率是否设置为 **115200**。 |
| 只能看到部分日志 | 先打开串口终端，再给开发板上电或重启，避免错过早期启动日志。 |
| 无法输入命令 | 确认系统已启动完成；按 **Enter** 激活控制台；检查串口工具是否处于可输入状态。 |